<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>phpManta - Mdoc - Template  reference</title>
<link href="reference-style.css" rel="stylesheet" type="text/css" />
</head>

<body>
<h1>Mdoc template reference</h1>
<p>This page provides author notes used to use the Mdoc template features.</p>
<h2>Syntax and terms </h2>
<p>A <span class="term">template</span> is an array of template elements, with at least two VIEW elements, VIEW:author and VIEW:public. </p>
<p>The <span class="term">element reference</span> in between bracketsis called the <span class="term">template variable</span>, example: {TREE.main.name}. </p>
<p>There are two types of template elements:</p>
<ul>
  <li>the <span class="term">data reference</span> (TREE.main.name) which provide a scalar or array value,</li>
<li>the <span class="term">template reference </span> (TREE.main.name?not_blank) which provide a substitution defined within the template array.</li>
</ul>
<p>The template variable syntax is: </p>
<blockquote>
  <p>{(<strong>[A-Z][A-Z0-9_\.]*</strong>)(\<strong>.[a-zA-Z0-9_\.]+</strong>)?(<strong>#[a-z0-9_]+</strong>)?(\<strong>?[=\!a-zA-Z0-9_-]+</strong>)} </p>
</blockquote>
<p>where: </p>
<ul>
  <li>the <strong>first</strong> pattern is called the <span class="term">branch</span> and is required,</li>
  <li>the <strong>second</strong> pattern is the  <span class="term">path</span> and is optional,</li>
  <li>the <strong>third</strong> pattern is the <span class="term">label</span> which is useful to include an array data several times in the same template view,</li>
  <li>the <strong>fourth</strong> pattern is called the <span class="term">redirection</span> and is optional. </li>
</ul>
<h2>Redirection ?blank and ?not_blank explained</h2>
<p>If you want to display a template element only if it is not blank, use the ?not_blank reference, for example:</p>
<ul>
  <li>TREE.function?not_blank =&gt; &quot;{TREE.function}&quot;<br />
  TREE.function?blank =&gt; &quot;&lt;p&gt;This library has no functions defined.&lt;/p&gt;\n&quot;<br />
  <br />
  </li>
<li>TREE.main.info.warning?not_blank =&gt; &quot;&lt;p&gt;&lt;b&gt;Warning: {TREE.main.info.warning}&lt;/b&gt;&lt;/p&gt;\n&quot;  </li>
</ul>
<p>If the complementary reference is missing and the test is false, the reference is cleared. This works  for ?empty and ?not_empty too, and also for ?exists and ?not_exists. </p>
<h2>Redirection ?=value and ?!=value explained</h2>
<p>If you want to display a template element only if it is equal to &quot;value&quot;, use the ?=value reference, for example:</p>
<ul>
  <li>TREE.main.type?=library =&gt; &quot;lib={TREE.main.name}&quot;<br />
    TREE.main.type?!=library =&gt; &quot;class={TREE.main.name}&quot;</li>
</ul>
<p>If the complementary reference is missing and the test is false, the reference is cleared. </p>
<p>Only simple string and numerical values are supported assuming they match the syntax <strong>[=\!a-zA-Z0-9_-]+</strong> in a Perl regular expression. </p>
<h2>Element :any explained</h2>
<p>Elements :any (and :first and :last) support <span class="term">scope</span> references.</p>
<p>Scope references in simple arrays are %Keyword and %Value references, for example:</p>
<ul>
  <li>TREE.main.info:any =&gt; &quot;&lt;tr&gt;&lt;td&gt;{INFO%Keyword}: &lt;/td&gt;&lt;td&gt; {INFO%Value}&lt;/td&gt;&lt;/tr&gt;\n&quot;<br />
    <br />
  where {INFO%Keyword} and {INFO%Value}  refer to the TREE[main][info][%Keyword] =&gt; %Value </li>
</ul>
<p>Scope references in associative arrays support <span class="term">path in a local scope data tree</span>:</p>
<ul>
  <li>TREE.function:any =&gt; &quot; &lt;dt&gt;{FUNCTION} :  {FUNCTION.description.short} -- {FUNCTION_URL}&lt;/dt&gt;\n&quot;<br />
    <br />
    where {FUNCTION} refers to the current scope itself (the function name) <br />
    where {FUNCTION.description.short} refers to FUNCTION[description][short] <br />
  where {FUNCTION_URL} refers to a regular template reference</li>
</ul>
<h2>Summary</h2>
<table  border="1" cellspacing="0" cellpadding="4">
  <tr>
    <th>Element reference </th>
    <th>Reference type</th>
    <th>Definition</th>
  </tr>
  <tr>
    <td>VIEW:author</td>
    <td>template</td>
    <td>The template used to build the documentation in &quot;author&quot; view level. </td>
  </tr>
  <tr>
    <td>VIEW:public</td>
    <td>template</td>
    <td>The template used to build the documentation in &quot;public&quot; view level. </td>
  </tr>
  <tr>
    <td>VIEW</td>
    <td>template</td>
    <td>This read-only element is set to the view level.</td>
  </tr>
  <tr>
    <td>ERRMSG:not_a_method</td>
    <td>template</td>
    <td>When template formating methods can't returned a valid template, they
      return a hard-coded error message which can be customized  as a template
      element. </td>
  </tr>
  <tr>
    <td>FLAG:smart_display</td>
    <td>template</td>
    <td>Set this flag &quot;off&quot; to disable XHTML smart display feature (default value
      is &quot;on&quot;). </td>
  </tr>
  <tr>
    <td>TREE.main.name</td>
    <td>data</td>
    <td>The file name from Mdoc-&gt;tree[main][name].</td>
  </tr>
  <tr>
    <td>TREE.method</td>
    <td>data</td>
    <td>The array of methods from Mdoc-&gt;tree[method] so the related :frame and :any elements are required. </td>
  </tr>
  <tr>
    <td>TREE.method:exclude</td>
    <td>data</td>
    <td>An array of keys to exclude values fom the  array of methods in all views.</td>
  </tr>
  <tr>
    <td>TREE.method:frame</td>
    <td>data</td>
    <td>The frame to embed the method array values. </td>
  </tr>
  <tr>
    <td>TREE.method:any</td>
    <td>data</td>
    <td>The element to embed one method array value. </td>
  </tr>
  <tr>
    <td>TREE.method:first</td>
    <td>data</td>
    <td>The element to embed the first method array value (instead of the :any element). </td>
  </tr>
  <tr>
    <td>TREE.method:last</td>
    <td>data</td>
    <td>The element to embed the last method array value (instead of the :any element). </td>
  </tr>
  <tr>
    <td>TREE.main.info.warning?not_blank</td>
    <td>data</td>
    <td>The element to embed the TREE.main.info.warning value if this data is not empty or is numeric zero.</td>
  </tr>
  <tr>
    <td>TREE.main.info.warning?blank</td>
    <td>data</td>
    <td>The element to embed the TREE.main.info.warning value if this data is   empty but not numeric zero.</td>
  </tr>
  <tr>
    <td>TREE.main.info.warning?not_empty</td>
    <td>data</td>
    <td>The element to embed the TREE.main.info.warning value if this data is not empty (in the PHP sense).</td>
  </tr>
  <tr>
    <td>TREE.main.info.warning?empty</td>
    <td>data</td>
    <td>The element to embed the TREE.main.info.warning value if this data is empty.</td>
  </tr>
  <tr>
    <td>TREE.main.info.warning?not_exists</td>
    <td>data</td>
    <td>The element to embed the TREE.main.info.warning value if this path doesn't exist in the data tree.</td>
  </tr>
  <tr>
    <td>TREE.main.info.warning?exists</td>
    <td>data</td>
    <td>The element to embed the TREE.main.info.warning value if this path exists in the data tree.</td>
  </tr>
  <tr>
    <td>TREE.main.type?=library</td>
    <td>data</td>
    <td>The element to embed the TREE.main.type value if its value is &quot;library&quot;.</td>
  </tr>
  <tr>
    <td>TREE.main.type?!=library</td>
    <td>data</td>
    <td>The element to embed the TREE.main.type value if its value is not equal to &quot;library&quot;.</td>
  </tr>
  <tr>
    <td>TREE.constant</td>
    <td>data</td>
    <td>The array of constants from Mdoc-&gt;tree[constant] so the related :frame and :any elements are required. </td>
  </tr>
  <tr>
    <td>TREE.constant#values</td>
    <td>data</td>
    <td>Another template instance for the array of methods from Mdoc-&gt;tree[method] so the related #values:frame and #values:any elements are required. </td>
  </tr>
  <tr>
    <td>TREE.constant#values?blank</td>
    <td>data</td>
    <td>A substitution for the array of constants frame if the array of values is empty (after filtering out the :exclude values).</td>
  </tr>
  <tr>
    <td>TREE.constant#values:frame</td>
    <td>data</td>
    <td>The frame to embed the method array values. </td>
  </tr>
  <tr>
    <td>TREE.constant#values:any</td>
    <td>data</td>
    <td>The element to embed one method array value. </td>
  </tr>
  <tr>
    <td>CONSTANT_URL</td>
    <td>template</td>
    <td>The template element 'CONSTANT_URL' will replace the template variable. </td>
  </tr>
  <tr>
    <td> Mdoc:DATA:<em>integer</em></td>
    <td>reserved</td>
    <td>This element is reserved to replace  data value references until  the last pass and avoid confusion with {TEMPLATE_LIKE} strings in Mdoc-&gt;tree values. The <em>integer</em> is the array index in fetch_data stack. </td>
  </tr>
</table>
<p>&nbsp;</p>
</body>
</html>
